Using the "Engine" Object

Using the "Engine" Object

We have already said that the “Engine” object represents the report's engine, which manages report construction. The process of arranging band(s) on a page can be managed by using the engine's properties and methods. First some theory.

The diagram below shows various dimensions of the report page.

The physical dimensions of the page are the “PaperWidth” and “PaperHeight” properties, visible in the object inspector when the page is selected. So the size of an A4 page is 210 x 297mm.

“PageWidth” and “PageHeight” are the dimensions of the printable region, which is usually less than the physical dimensions of the page. The size of the printable region is dependent on the report page properties “LeftMargin”, “TopMargin”, “RightMargin” and “BottomMargin”. The printable region’s size in pixels is returned by the “Engine.PageWidth” and “Engine.PageHeight” functions.

Finally, “FreeSpace” is the height of the free space on a page. If there is a "Page Footer" band on the page, its height is taken into account when calculating the “FreeSpace”. This height is returned in pixels by the “Engine.FreeSpace” function. Note that after displaying the next band the free space is reduced on the page, this is taken into account when calculating the “FreeSpace”.

How are report pages constructed? The FastReport core displays bands on a page as long as there is enough free space. When there is no more free space left the “Page Footer" band is printed (if required) and a new blank page is created. As already said, after displaying the next band the height of free space is reduced. Moreover, display of the next band begins from the current position, which is defined by coordinates on the X-axis and the Y-axis. The current position is returned by “Engine.CurX” and “Engine.CurY” respectively. After printing the next band, CurY automatically increases by the height of the printed band. After a new page is created “CurY” equals “0.” “CurX” is changed when printing multi-column reports.

“Engine.CurX” and “Engine.CurY” are available not only for reading but also for writing. This means that bands can be shifted by incrementing or decrementing these values. For example, in a report resembling this:

It can be printed in the following way:

This is achieved by writing a handler for the band's “OnBeforePrint” event:

procedure MasterData1OnBeforePrint(Sender: TfrxComponent);

begin

  Engine.CurX := Engine.CurX + 5;

end;

Changing “CurY” can make bands overlap, for example:

Achieved by this script:

procedure MasterData1OnBeforePrint(Sender: TfrxComponent);

begin

  Engine.CurY := Engine.CurY - 15;

end;

The “Engine.NewPage” method inserts a page break at any required point in a report, following which printing continues from the top of the new output page. In our example a break can be inserted after printing the second record:

procedure MasterData1OnAfterPrint(Sender: TfrxComponent);

begin

   if <Line> = 2 then

     Engine.NewPage;

end;

Note that we used the “OnAfterPrint” event (that is to say, after the band has been printed). Also note that the “Line” system variable returns the sequential number of the record.

The “Engine.NewColumn” method inserts a column break in multi-columned reports. If there are no more free columns left on the page then a new page is created.

Invoice with Payment Orders

The following example is presented on printout of orders and invoices with payment orders. They are available only for slovenian and croatian legislation. Such reports are '2U2 - Invoice - UPN - Form' for slovenian and '2U7 - Invoice - HUB 3A - Form' for croatian legislation. You can see design of these report opening report designer from the Report register.

We want to print payment order always exact at the bottom of the page. To force this behavior we set current vertical position (Engine.CurY) of report summary band so that there is exact enough space to display it on this page. We do this with the next code:

procedure UPNOnBeforePrint(Sender: TfrxComponent);
begin
  ...
  Engine.CurY := Engine.CurY + Engine.FreeSpace - UPN.Height - 1;
end; 

When creating the report payment order will overlap existing text if is to high. So we must correct our code to print payment order on the next page in this case.

procedure UPNOnBeforePrint(Sender: TfrxComponent);
begin
  ...
  if Engine.CurY > Engine.CurY + Engine.FreeSpace - UPN.Height - 1 then
    Engine.NewPage;  
  Engine.CurY := Engine.CurY + Engine.FreeSpace - UPN.Height - 1;
end;